remark-slug

What is remark-slug?

The remark-slug npm package is a plugin for the remark Markdown processor that automatically adds slugs to headings in a Markdown document. This is useful for generating links to specific sections of the document, enhancing navigation and accessibility.

What are remark-slug's main functionalities?

Automatic Slug Generation

This feature automatically generates slugs for each heading in a Markdown document. The code sample shows how to use remark-slug with remark and remark-html to convert a Markdown heading into HTML with a slug.

const remark = require('remark');
const remarkHtml = require('remark-html');
const remarkSlug = require('remark-slug');

remark()
  .use(remarkSlug)
  .use(remarkHtml)
  .process('# Hello world', function (err, file) {
    console.log(String(file));
  });

Other packages similar to remark-slug

markdown-it-anchor

markdown-it-anchor is a plugin for the markdown-it Markdown parser. Similar to remark-slug, it adds anchors to headings in Markdown documents. While remark-slug is specifically designed for the remark ecosystem, markdown-it-anchor serves the markdown-it ecosystem, offering similar functionality but within a different processing environment.

rehype-slug

rehype-slug is a plugin for the rehype processor, which is part of the unified.js ecosystem, similar to remark. It adds slugs to HTML elements processed through rehype. This is akin to what remark-slug does but is applied directly to HTML rather than Markdown, making it suitable for projects that work with HTML content at a later stage in the content pipeline.

README

remark-slug

Add anchors to remark heading nodes using GitHub’s algorithm.

:warning: This is often useful when compiling to HTML. If you’re doing that, it’s probably smarter to use remark-rehype and rehype-slug and benefit from the rehype ecosystem.

Installation

npm:

npm install remark-slug

Usage

Say we have the following file, example.md:

# Lorem ipsum 😪

## dolor—sit—amet

### consectetur & adipisicing

#### elit

##### elit

And our script, example.js, looks as follows:

var fs = require('fs');
var unified = require('unified');
var markdown = require('remark-parse');
var slug = require('remark-slug');
var remark2rehype = require('remark-rehype');
var html = require('rehype-stringify');

unified()
  .use(markdown)
  .use(slug)
  .use(remark2rehype)
  .use(html)
  .process(fs.readFileSync('example.md'), function (err, file) {
    if (err) throw err;
    console.log(String(file));
  });

Now, running node example yields:

<h1 id="lorem-ipsum-">Lorem ipsum 😪</h1>
<h2 id="dolorsitamet">dolor—sit—amet</h2>
<h3 id="consectetur--adipisicing">consectetur &#x26; adipisicing</h3>
<h4 id="elit">elit</h4>
<h5 id="elit-1">elit</h5>

API

remark.use(slug)

Adds slugs to markdown headings.

Uses github-slugger (thus creating GitHub style ids).

Sets data.id, data.hProperties.id on heading nodes. The first can be used by any plugin as a unique identifier, the second tells remark-html to use its value as an id attribute. remark-slug does not overwrite these values when they already exist.

Related

• rehype-slug — Add slugs to headings in HTML

License

MIT © Titus Wormer